<HTML>
<HEAD>
  <TITLE>IO::Scalar</TITLE>
</HEAD>
<BODY 
       bgcolor="#FFFFFF" link="#CC3366" vlink="#993366" alink="#FF6666">
<FONT FACE="sans-serif" SIZE=-1><A HREF="http://www.zeegee.com" TARGET="_top"><IMG SRC="icons/zeegee.gif" ALT="ZeeGee Software" ALIGN="RIGHT" BORDER="0"></A><A NAME="__TOP__"><H1>IO::Scalar</H1>
</A><UL>
<LI> <A HREF="#NAME">NAME</A>
<LI> <A HREF="#SYNOPSIS">SYNOPSIS</A>
<LI> <A HREF="#DESCRIPTION">DESCRIPTION</A>
<LI> <A HREF="#PUBLIC_INTERFACE">PUBLIC INTERFACE</A>
<UL>
<LI> <A HREF="#Construction">Construction</A>
<LI> <A HREF="#Input_and_output">Input and output</A>
<LI> <A HREF="#Seeking_telling_and_other_attributes">Seeking/telling and other attributes</A>
</UL>
<LI> <A HREF="#WARNINGS">WARNINGS</A>
<LI> <A HREF="#VERSION">VERSION</A>
<LI> <A HREF="#AUTHORS">AUTHORS</A>
<UL>
<LI> <A HREF="#Principal_author">Principal author</A>
<LI> <A HREF="#Other_contributors">Other contributors</A>
</UL>
<LI> <A HREF="#SEE_ALSO">SEE ALSO</A>
</UL>
</A>

<P><HR>
<A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A>


<P>IO::Scalar - IO:: interface for reading/writing a scalar



<P><HR>
<A NAME="SYNOPSIS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SYNOPSIS</H2></A>


<P>Perform I/O on strings, using the basic OO interface...

<FONT SIZE=3 FACE="courier"><PRE>
    use 5.005;
    use IO::Scalar;
    $data = &quot;My message:\n&quot;;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Open a handle on a string, and append to it:
    $SH = new IO::Scalar \$data;
    $SH-&gt;print(&quot;Hello&quot;);       
    $SH-&gt;print(&quot;, world!\nBye now!\n&quot;);  
    print &quot;The string is now: &quot;, $data, &quot;\n&quot;;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Open a handle on a string, read it line-by-line, then close it:
    $SH = new IO::Scalar \$data;
    while (defined($_ = $SH-&gt;getline)) { 
	print &quot;Got line: $_&quot;;
    }
    $SH-&gt;close;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Open a handle on a string, and slurp in all the lines:
    $SH = new IO::Scalar \$data;
    print &quot;All lines:\n&quot;, $SH-&gt;getlines; 
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Get the current position (either of two ways):
    $pos = $SH-&gt;getpos;         
    $offset = $SH-&gt;tell;  
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Set the current position (either of two ways):
    $SH-&gt;setpos($pos);        
    $SH-&gt;seek($offset, 0);
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Open an anonymous temporary scalar:
    $SH = new IO::Scalar;
    $SH-&gt;print(&quot;Hi there!&quot;);
    print &quot;I printed: &quot;, ${$SH-&gt;sref}, &quot;\n&quot;;      ### get at value
</PRE></FONT>

<P>Don't like OO for your I/O?  No problem.  
Thanks to the magic of an invisible tie(), the following now 
works out of the box, just as it does with IO::Handle:

<FONT SIZE=3 FACE="courier"><PRE>
    use 5.005;
    use IO::Scalar;
    $data = &quot;My message:\n&quot;;
     
    ### Open a handle on a string, and append to it:
    $SH = new IO::Scalar \$data;
    print $SH &quot;Hello&quot;;    
    print $SH &quot;, world!\nBye now!\n&quot;;
    print &quot;The string is now: &quot;, $data, &quot;\n&quot;;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Open a handle on a string, read it line-by-line, then close it:
    $SH = new IO::Scalar \$data;
    while (&lt;$SH&gt;) {
	print &quot;Got line: $_&quot;;
    }
    close $SH;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Open a handle on a string, and slurp in all the lines:
    $SH = new IO::Scalar \$data;
    print &quot;All lines:\n&quot;, &lt;$SH&gt;;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Get the current position (WARNING: requires 5.6):
    $offset = tell $SH;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Set the current position (WARNING: requires 5.6):
    seek $SH, $offset, 0;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Open an anonymous temporary scalar:
    $SH = new IO::Scalar;
    print $SH &quot;Hi there!&quot;;
    print &quot;I printed: &quot;, ${$SH-&gt;sref}, &quot;\n&quot;;      ### get at value
</PRE></FONT>

<P>And for you folks with 1.x code out there: the old tie() style still works,
though this is <I>unnecessary and deprecated</I>:

<FONT SIZE=3 FACE="courier"><PRE>
    use IO::Scalar;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Writing to a scalar...
    my $s; 
    tie *OUT, 'IO::Scalar', \$s;
    print OUT &quot;line 1\nline 2\n&quot;, &quot;line 3\n&quot;;
    print &quot;String is now: $s\n&quot;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Reading and writing an anonymous scalar... 
    tie *OUT, 'IO::Scalar';
    print OUT &quot;line 1\nline 2\n&quot;, &quot;line 3\n&quot;;
    tied(OUT)-&gt;seek(0,0);
    while (&lt;OUT&gt;) { 
        print &quot;Got line: &quot;, $_;
    }
</PRE></FONT>

<P>Stringification works, too!

<FONT SIZE=3 FACE="courier"><PRE>
    my $SH = new IO::Scalar \$data;
    print $SH &quot;Hello, &quot;;
    print $SH &quot;world!&quot;;
    print &quot;I printed: $SH\n&quot;;
</PRE></FONT>


<P><HR>
<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A>


<P>This class is part of the IO::Stringy distribution;
see <A HREF="IO/Stringy.pm.html">IO::Stringy</A> for change log and general information.


<P>The IO::Scalar class implements objects which behave just like 
IO::Handle (or FileHandle) objects, except that you may use them 
to write to (or read from) scalars.  These handles are 
automatically tiehandle'd (though please see <A HREF="#WARNINGS">WARNINGS</A>
for information relevant to your Perl version).


<P>Basically, this:

<FONT SIZE=3 FACE="courier"><PRE>
    my $s;
    $SH = new IO::Scalar \$s;
    $SH-&gt;print(&quot;Hel&quot;, &quot;lo, &quot;);         ### OO style
    $SH-&gt;print(&quot;world!\n&quot;);            ### ditto
</PRE></FONT>

<P>Or this:

<FONT SIZE=3 FACE="courier"><PRE>
    my $s;
    $SH = tie *OUT, 'IO::Scalar', \$s;
    print OUT &quot;Hel&quot;, &quot;lo, &quot;;           ### non-OO style
    print OUT &quot;world!\n&quot;;              ### ditto
</PRE></FONT>

<P>Causes $s to be set to:    

<FONT SIZE=3 FACE="courier"><PRE>
    &quot;Hello, world!\n&quot; 
</PRE></FONT>


<P><HR>
<A NAME="PUBLIC_INTERFACE"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> PUBLIC INTERFACE</H2></A>



<P><HR>
<A NAME="Construction"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Construction</H3></A>



<DL>
<P><DT><B><A NAME="item:new">new [ARGS...]</A></B></DT>
<DD>
<I>Class method.</I>
Return a new, unattached scalar handle.  
If any arguments are given, they're sent to open().

<P><DT><B><A NAME="item:open">open [SCALARREF]</A></B></DT>
<DD>
<I>Instance method.</I>
Open the scalar handle on a new scalar, pointed to by SCALARREF.
If no SCALARREF is given, a &quot;private&quot; scalar is created to hold
the file data.


<P>Returns the self object on success, undefined on error.

<P><DT><B><A NAME="item:opened">opened</A></B></DT>
<DD>
<I>Instance method.</I>
Is the scalar handle opened on something?

<P><DT><B><A NAME="item:close">close</A></B></DT>
<DD>
<I>Instance method.</I>
Disassociate the scalar handle from its underlying scalar.
Done automatically on destroy.

</DL>



<P><HR>
<A NAME="Input_and_output"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Input and output</H3></A>



<DL>
<P><DT><B><A NAME="item:flush">flush</A></B></DT>
<DD>
<I>Instance method.</I>
No-op, provided for OO compatibility.

<P><DT><B><A NAME="item:getc">getc</A></B></DT>
<DD>
<I>Instance method.</I>
Return the next character, or undef if none remain.

<P><DT><B><A NAME="item:getline">getline</A></B></DT>
<DD>
<I>Instance method.</I>
Return the next line, or undef on end of string.  
Can safely be called in an array context.
Currently, lines are delimited by &quot;\n&quot;.

<P><DT><B><A NAME="item:getlines">getlines</A></B></DT>
<DD>
<I>Instance method.</I>
Get all remaining lines.
It will croak() if accidentally called in a scalar context.

<P><DT><B><A NAME="item:print">print ARGS...</A></B></DT>
<DD>
<I>Instance method.</I>
Print ARGS to the underlying scalar.  


<P><B>Warning:</B> this continues to always cause a seek to the end 
of the string, but if you perform seek()s and tell()s, it is
still safer to explicitly seek-to-end before subsequent print()s.

<P><DT><B><A NAME="item:read">read BUF, NBYTES, [OFFSET]</A></B></DT>
<DD>
<I>Instance method.</I>
Read some bytes from the scalar.
Returns the number of bytes actually read, 0 on end-of-file, undef on error.

<P><DT><B><A NAME="item:write">write BUF, NBYTES, [OFFSET]</A></B></DT>
<DD>
<I>Instance method.</I>
Write some bytes to the scalar.

<P><DT><B><A NAME="item:sysread">sysread BUF, LEN, [OFFSET]</A></B></DT>
<DD>
<I>Instance method.</I>
Read some bytes from the scalar.
Returns the number of bytes actually read, 0 on end-of-file, undef on error.

<P><DT><B><A NAME="item:syswrite">syswrite BUF, NBYTES, [OFFSET]</A></B></DT>
<DD>
<I>Instance method.</I>
Write some bytes to the scalar.

</DL>



<P><HR>
<A NAME="Seeking_telling_and_other_attributes"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Seeking/telling and other attributes</H3></A>



<DL>
<P><DT><B><A NAME="item:autoflush">autoflush</A></B></DT>
<DD>
<I>Instance method.</I>
No-op, provided for OO compatibility.

<P><DT><B><A NAME="item:binmode">binmode</A></B></DT>
<DD>
<I>Instance method.</I>
No-op, provided for OO compatibility.

<P><DT><B><A NAME="item:clearerr">clearerr</A></B></DT>
<DD>
<I>Instance method.</I>  Clear the error and EOF flags.  A no-op.

<P><DT><B><A NAME="item:eof">eof</A></B></DT>
<DD>
<I>Instance method.</I>  Are we at end of file?

<P><DT><B><A NAME="item:seek">seek OFFSET, WHENCE</A></B></DT>
<DD>
<I>Instance method.</I>  Seek to a given position in the stream.

<P><DT><B><A NAME="item:sysseek">sysseek OFFSET, WHENCE</A></B></DT>
<DD>
<I>Instance method.</I> Identical to <CODE>seek OFFSET, WHENCE</CODE>, <I>q.v.</I>

<P><DT><B><A NAME="item:tell">tell</A></B></DT>
<DD>
<I>Instance method.</I>
Return the current position in the stream, as a numeric offset.

<P><DT><B><A NAME="item:use_RS">use_RS [YESNO]</A></B></DT>
<DD>
<I>Instance method.</I>
Obey the curent setting of $/, like IO::Handle does?
Default is false in 1.x, true in 2.x and later.

<P><DT><B><A NAME="item:setpos">setpos POS</A></B></DT>
<DD>
<I>Instance method.</I>
Set the current position, using the opaque value returned by <CODE>getpos()</CODE>.

<P><DT><B><A NAME="item:getpos">getpos</A></B></DT>
<DD>
<I>Instance method.</I>
Return the current position in the string, as an opaque object.

<P><DT><B><A NAME="item:sref">sref</A></B></DT>
<DD>
<I>Instance method.</I>
Return a reference to the underlying scalar.

</DL>



<P><HR>
<A NAME="WARNINGS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> WARNINGS</H2></A>


<P>Perl's TIEHANDLE spec was incomplete prior to 5.005_57;
it was missing support for <CODE>seek()</CODE>, <CODE>tell()</CODE>, and <CODE>eof()</CODE>.
Attempting to use these functions with an IO::Scalar will not work
prior to 5.005_57. IO::Scalar will not have the relevant methods 
invoked; and even worse, this kind of bug can lie dormant for a while.
If you turn warnings on (via <CODE>$^W</CODE> or <CODE>perl -w</CODE>),
and you see something like this...

<FONT SIZE=3 FACE="courier"><PRE>
    attempt to seek on unopened filehandle
</PRE></FONT>

<P>...then you are probably trying to use one of these functions
on an IO::Scalar with an old Perl.  The remedy is to simply
use the OO version; e.g.:

<FONT SIZE=3 FACE="courier"><PRE>
    $SH-&gt;seek(0,0);    ### GOOD: will work on any 5.005
    seek($SH,0,0);     ### WARNING: will only work on 5.005_57 and beyond
</PRE></FONT>


<P><HR>
<A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A>


<P>$Id: Scalar.pm.html 625 2005-06-09 14:20:30Z nj7w $



<P><HR>
<A NAME="AUTHORS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHORS</H2></A>



<P><HR>
<A NAME="Principal_author"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Principal author</H3></A>


<P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>).
President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>).



<P><HR>
<A NAME="Other_contributors"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Other contributors</H3></A>


<P>The full set of contributors always includes the folks mentioned
in <A HREF="IO/Stringy.pm.html#CHANGE_LOG">CHANGE LOG</A>.  But just the same, special
thanks to the following individuals for their invaluable contributions
(if I've forgotten or misspelled your name, please email me!):


<P><I>Andy Glew,</I>
for contributing <CODE>getc()</CODE>.


<P><I>Brandon Browning,</I>
for suggesting <CODE>opened()</CODE>.


<P><I>David Richter,</I>
for finding and fixing the bug in <CODE>PRINTF()</CODE>.


<P><I>Eric L. Brine,</I>
for his offset-using read() and write() implementations. 


<P><I>Richard Jones,</I>
for his patches to massively improve the performance of <CODE>getline()</CODE>
and add <CODE>sysread</CODE> and <CODE>syswrite</CODE>.


<P><I>B. K. Oxley (binkley),</I>
for stringification and inheritance improvements,
and sundry good ideas.


<P><I>Doug Wilson,</I>
for the IO::Handle inheritance and automatic tie-ing.



<P><HR>
<A NAME="SEE_ALSO"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SEE ALSO</H2></A>


<P><A HREF="IO/String.pm.html">IO::String</A>, which is quite similar but which was designed
more-recently and with an IO::Handle-like interface in mind, 
so you could mix OO- and native-filehandle usage without using tied().  


<P><I>Note:</I> as of version 2.x, these classes all work like 
their IO::Handle counterparts, so we have comparable
functionality to IO::String.

<P><HR>
<ADDRESS><FONT SIZE=-1>
Generated Wed Aug  8 03:39:45 2001 by cvu_pod2html
</FONT></ADDRESS>
</FONT></BODY>
</HTML>
